home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / DOpus_SDK_5.5 / docs / popup.doc < prev    next >
Text File  |  1996-09-05  |  6KB  |  139 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/DoPopUpMenu
  4. dopus5.library/GetPopUpItem
  5. dopus5.library/DoPopUpMenu                         dopus5.library/DoPopUpMenu
  6.  
  7.     NAME
  8.         DoPopUpMenu - display a popup menu
  9.  
  10.     SYNOPSIS
  11.         DoPopUpMenu(window, menu, itemptr, button)
  12.                       A0     A1      A2      D0
  13.  
  14.         USHORT DoPopUpMenu(struct Window *, PopUpMenu *, PopUpItem **, USHORT);
  15.  
  16.     FUNCTION
  17.         This routine displays a popup menu. The PopUpMenu structure must be
  18.         initialised as follows:
  19.  
  20.             item_list - a list of the menu items
  21.  
  22.             locale    - a pointer to an initialised DOpusLocale structure
  23.  
  24.             flags     - menu flags. Currently supported flags are:
  25.  
  26.                             POPUPMF_HELP    - menu supports help via the user
  27.                                               pressing the help key
  28.  
  29.                             POPUPMF_REFRESH - the callback function supplied
  30.                                               should be used to refresh the
  31.                                               parent window
  32.  
  33.                             POPUPMF_ABOVE   - the popup menu should open
  34.                                               above the parent window, instead
  35.                                               of over the current mouse
  36.                                               position
  37.  
  38.             callback  - pointer to your refresh callback function, or NULL
  39.  
  40.         The callback function is a function that you define to handle the
  41.         situation when the parent window needs to be refreshed. If the parent
  42.         window is simplerefresh, you should provide this function. The function
  43.         has the following prototype:
  44.  
  45.             void __asm refresh_callback(    register __d0 ULONG type,
  46.                                             register __a0 struct Window *window,
  47.                                             register __a1 ULONG userdata )
  48.  
  49.         The routine will be called whenever the parent window needs to be
  50.         refreshed. 'type' is the IDCMP message type; usually
  51.         IDCMP_REFRESHWINDOW. 'window' is a pointer to the parent window, and
  52.         'userdata' is the userdata field of the PopUpMenu structure.
  53.  
  54.         The 'item_list' parameter is a MinList containing the items of the
  55.         popup menu. Each node on this list is a PopUpItem structure, which is
  56.         defined as follows :
  57.  
  58.             item_name - pointer to item name
  59.  
  60.             id        - item ID
  61.  
  62.             flags     - item flags. Currently supported flags are:
  63.  
  64.                             POPUPF_LOCALE   - signifies that 'item_name' is
  65.                                               not a pointer to a string, but
  66.                                               is a locale ID representing a
  67.                                               string in the supplied locale.
  68.  
  69.                             POPUPF_CHECKIT  - item can be checked, much like
  70.                                               CHECKIT in Intuition menus
  71.  
  72.                             POPUPF_CHECKED  - item starts out checked, much
  73.                                               like CHECKED in Intuition menus
  74.  
  75.                             POPUPF_SUB      - item has sub-items
  76.  
  77.                             POPUPF_DISABLED - item is disabled
  78.  
  79.             data      - unless POPUPF_SUB is set, this is a userdata field
  80.                         that can be set to anything. If POPUPF_SUB is set, this
  81.                         field must point to an initialised MinList containing
  82.                         the PopUpItem structures for the sub-menu. You can
  83.                         have up to four levels of sub-menus.
  84.  
  85.         Set 'item_name' to the special value POPUP_BARLABEL to produce a
  86.         separator bar in the menu.
  87.  
  88.     INPUTS
  89.         window  - Parent window to open menu over
  90.         menu    - PopUpMenu to open
  91.         itemptr - Pointer to location to receive a pointer to the selected
  92.                   item
  93.         button  - The code of the mouse button pressed to generate this menu.
  94.                   This is used to control which mouse button release will
  95.                   remove the menu (eg, if you pass SELECTDOWN for the 'button'
  96.                   value, the menu will be removed on a SELECTUP event)
  97.  
  98.     RESULT
  99.         Returns -1 if no item was selected. If an item was selected,
  100.         the item ID is returned, and the address of the PopUpItem structure
  101.         is stored in 'itemptr'. If the user pressed the help key over an item
  102.         and the POPUPMF_HELP flag is set, the POPUP_HELPFLAG flag will be
  103.         set in the returned item ID.
  104.  
  105.     SEE ALSO
  106.         GetPopUpItem()
  107.  
  108. dopus5.library/GetPopUpItem                       dopus5.library/GetPopUpItem
  109.  
  110.     NAME
  111.         GetPopUpItem - find a PopUpItem by ID
  112.  
  113.     SYNOPSIS
  114.         GetPopUpItem(menu, id)
  115.                       A0   D0
  116.  
  117.         PopUpItem *GetPopUpItem(PopUpMenu *, USHORT);
  118.  
  119.     FUNCTION
  120.         This searches the supplied menu for a PopUpItem with the specified ID,
  121.         and returns a pointer to it.
  122.  
  123.     INPUTS
  124.         menu - PopUpMenu to search
  125.         id   - ID to search for
  126.  
  127.     RESULT
  128.         Returns a pointer to the PopUpItem if found, or else NULL. This routine
  129.         supports one level of sub-menus, and will not find an item that is
  130.         more than one sub-menu deep.
  131.  
  132.     NOTES
  133.         This routine is useful in allowing you to find an item to set the state
  134.         of the POPUPF_CHECKED and POPUPF_DISABLED flags.
  135.  
  136.     SEE ALSO
  137.         DoPopUpMenu()
  138.  
  139.